<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>pthread_rwlock_wrlock</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_1630">&nbsp;</a>NAME</h4><blockquote>
pthread_rwlock_wrlock, pthread_rwlock_trywrlock
- lock a read-write lock object for writing
</blockquote><h4><a name = "tag_000_007_1631">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="pthread.h.html">pthread.h</a>&gt;

int pthread_rwlock_wrlock(pthread_rwlock_t <i>*rwlock</i>);
int pthread_rwlock_trywrlock(pthread_rwlock_t <i>*rwlock</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_1632">&nbsp;</a>DESCRIPTION</h4><blockquote>
The 
<i>pthread_rwlock_wrlock()</i>
function applies a write lock to
the read-write lock referenced by <i>rwlock</i>. The
calling thread acquires the write lock if no other thread
(reader or writer) holds the read-write lock <i>rwlock</i>.
Otherwise, the thread blocks (that is, does not return from the
<i>pthread_rwlock_wrlock()</i>
call) until it can
acquire the lock. Results are undefined if the calling thread
holds the read-write lock (whether a read or write
lock) at the time the call is made.
<p>
Implementations are allowed to favour writers over
readers to avoid writer starvation.
<p>
The function 
<i>pthread_rwlock_trywrlock()</i>
applies a write lock
like the 
<i>pthread_rwlock_wrlock()</i>
function, with the exception that the function fails if any
thread currently holds <i>rwlock</i> (for reading or writing).
<p>
Results are undefined if any of these functions are called with
an uninitialised read-write lock.
<p>
If a signal is delivered to a thread waiting for a read-write
lock for writing, upon return from the signal handler
the thread resumes waiting for the read-write lock for
writing as if it was not interrupted.
</blockquote><h4><a name = "tag_000_007_1633">&nbsp;</a>RETURN VALUE</h4><blockquote>
If successful, the 
<i>pthread_rwlock_wrlock()</i>
function returns zero. 
Otherwise, an error number is returned
to indicate the error.
<p>
The function 
<i>pthread_rwlock_trywrlock()</i>
returns zero if the
lock for writing on the read-write lock object
referenced by <i>rwlock</i> is acquired. 
Otherwise an error number is
returned to indicate the error.
</blockquote><h4><a name = "tag_000_007_1634">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>pthread_rwlock_trywrlock()</i>
function will fail if:
<dl compact>

<dt>[EBUSY]<dd>
The read-write lock could not be acquired for writing because it
was already locked for reading or writing.

</dl>
<p>
The
<i>pthread_rwlock_wrlock()</i>
and
<i>pthread_rwlock_trywrlock()</i>
functions may fail if:
<dl compact>

<dt>[EINVAL]<dd>
The value specified by <i>rwlock</i> does not refer to an initialised
read-write lock object.

<dt>[EDEADLK]<dd>
The current thread already owns the read-write lock for writing or
reading.

</dl>
</blockquote><h4><a name = "tag_000_007_1635">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1636">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
Similar functions are being developed by IEEE PASC.
In keeping with its objective of ensuring that CAE
Specifications are fully aligned with formal standards, The Open Group
intends to add any new interfaces adopted by an official IEEE standard
in this area.
<p>
Realtime applications may encounter priority inversion when using
read-write locks.
The problem occurs when a high priority thread &quot;locks&quot; a read-write
lock that is about to be &quot;unlocked&quot; by a low priority thread, but
the low priority thread is preempted by a medium priority thread.
This scenario leads to priority inversion; a high priority thread is
blocked by lower priority threads for an unlimited period of time.
During system design, realtime programmers must take into account the
possibility of this kind of priority inversion.
They can deal with it in a number of ways, such as by having critical
sections that are guarded by read-write locks execute at a high
priority, so that a thread cannot be preempted while executing in its
critical section.
</blockquote><h4><a name = "tag_000_007_1637">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1638">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="pthread.h.html">&lt;pthread.h&gt;</a></i>,
<i><a href="pthread_rwlock_init.html">pthread_rwlock_init()</a></i>,
<i><a href="pthread_rwlock_unlock.html">pthread_rwlock_unlock()</a></i>,
<i><a href="pthread_rwlockattr_init.html">pthread_rwlockattr_init()</a></i>,
<i><a href="pthread_rwlock_rdlock.html">pthread_rwlock_rdlock()</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
